ButtonBar

Kind of class:class
Inherits from:UIComponent < MovieClip
Classpath:gfx.controls.ButtonBar
File last modified:Tuesday, 29 June 2010, 09:03:27
The ButtonBar is similar to the ButtonGroup although it has a visual representation. It is also able to create Button instances on the fly based on a DataProvider. The ButtonBar is useful for creating dynamic tab-bar like UI elements.

Inspectable Properties
Although the ButtonBar component has no content (represented simply as a small circle on the Stage in Flash Studio), it does contain several inspectable properties. The majority of them deal with the placement settings of the Button instances created by the ButtonBar.
  • visible: Hides the ButtonBar if set to false.
  • disabled: Disables the ButtonBar if set to true.
  • itemRenderer: Linkage ID of the Button component symbol. This symbol will be instantiated as needed based on the data assigned to the ButtonBar.
  • direction: Button placement. Horizontal will place the Button instances side-by-side, while vertical will stack them on top of each other.
  • spacing: The spacing between the Button instances. Affects only the current direction (see direction property).
  • autoSize: Determines if child buttons will scale to fit the text that it contains and which direction to align the resized buttons. Setting the autoSize property to autoSize="none" will leave the buttons' current size unchanged.
  • buttonWidth: Sets a common width to all Button instances. If autoSize is set to true this property is ignored.
  • enableInitCallback: If set to true, _global.CLIK_loadCallback() will be fired when a component is loaded and _global.CLIK_unloadCallback will be called when the component is unloaded. These methods receive the instance name, target path, and a reference the component as parameters. _global.CLIK_loadCallback and _global.CLIK_unloadCallback should be overriden from the game engine using GFx FunctionObjects.
States
The CLIK ButtonBar does not have any visual states because its managed Button components are used to display the group state.

Events
All event callbacks receive a single Object parameter that contains relevant information about the event. The following properties are common to all events.
  • type: The event type.
  • target: The target that generated the event.
The events generated by the ButtonBar component are listed below. The properties listed next to the event are provided in addition to the common properties.
  • show: The component’s visible property has been set to true at runtime.
  • hide: The component’s visible property has been set to false at runtime.
  • focusIn: The component has received focus.
  • focusOut: The component has lost focus.
  • change: A new button from the group has been selected.
    • index: The selected index of the ButtonBar. Number type. Values 0 to number of buttons minus 1.
    • renderer: The selected Button. CLIK Button type.
    • item: The selected item from the dataProvider. AS2 Object type.
    • data: The data value of the selected dataProvider item. AS2 Object type.
  • itemClick: A button in the group has been clicked.
    • index: The ButtonBar index of the Button that was clicked. Number type. Values 0 to number of buttons minus 1.
    • item: The selected item from the dataProvider. AS2 Object type.
    • data: The data value of the selected dataProvider item. AS2 Object type.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
Component metadata:
    InspectableList
    "autoSize"
    "buttonWidth"
    "direction"
    "disabled"
    "enableInitCallback"
    "itemRenderer"
    "spacing"
    "visible"

    Summary


    Constructor
    Instance properties
    • disabled
    • dataProvider
      • The list of buttons to display.
    • itemRenderer
      • Set the linkage for each itemRenderer.
    • spacing
      • The spacing between each item in pixels.
    • direction
      • The direction the buttons draw.
    • autoSize
      • Determines if the buttons auto-size to fit their label.
    • buttonWidth
      • The width of each button.
    • selectedIndex
      • The 0-base index of the selected button.
    • selectedItem
      • The item at the selectedIndex in the DataProvider.
    • data
      • The data property of the selectedItem.
    • labelField
      • The name of the field in the dataProvider model to be displayed as the label for itemRenderers.
    • labelFunction
      • The function used to determine the label for itemRenderers.
    Instance properties inherited from UIComponent
    __height __width _disabled _displayFocus _focused addEventListener cleanUpEvents disabled dispatchEvent displayFocus enableInitCallback focused focusHandlerReference focusTarget hasEventListener height initialized invalidationIntervalID removeAllEventListeners removeEventListener sizeIsInvalid soundMap visible width
    Class methods
    Class methods inherited from UIComponent
    createInstance
    Instance methods
    Instance methods inherited from UIComponent
    changeFocus configUI dispatchEventAndSound dispatchEventToGame draw handleInput initSize invalidate onLoad onLoadImpl onMouseWheel onUnload scrollWheel setSize toString validateNow

    Constructor

    ButtonBar

    function ButtonBar (
    )

    The constructor is called when a ButtonBar or a sub-class of ButtonBar is instantiated on stage or by using UIComponent.createInstance() in ActionScript. This component can not be instantiated using new syntax. When creating new components that extend ButtonBar, ensure that a super() call is made first in the constructor.

    Instance properties

    autoSize

    autoSize:String
    (read,write)

    Determines if the buttons auto-size to fit their label. This parameter will only be applied if the itemRenderer supports it.

    buttonWidth

    buttonWidth:Number
    (read,write)

    The width of each button. Overrides the autoSize property when set. Set to 0 to let the component auto-size.

    data

    data:Object
    (read)

    The data property of the selectedItem.
    See also:

    dataProvider

    dataProvider:Object
    (read,write)

    The list of buttons to display. Unlike list-based components, this is just an Array. The Array can contain Objects or Strings, and the itemToLabel method will determine the resulting text label for each button.
    See also:

    direction

    direction:String
    (read,write)

    The direction the buttons draw. When the direction is set to "horizontal", the buttons will draw on the same y-coordinate, with the spacing between each instance. When the direction is set to "vertical", the buttons will draw with the same x-coordinate, with the spacing between each instance.
    See also:

    disabled

    disabled:Boolean
    (read,write)

    itemRenderer

    itemRenderer:String
    (read,write)

    Set the linkage for each itemRenderer. When the linkage changes, the ButtonBar will be redrawn.

    labelField

    labelField:String
    (read,write)

    The name of the field in the dataProvider model to be displayed as the label for itemRenderers. A labelFunction will be used over a labelField if it is defined.

    labelFunction

    labelFunction:Function
    (read,write)

    The function used to determine the label for itemRenderers. A labelFunction will override a labelField if it is defined.

    selectedIndex

    selectedIndex:Number
    (read,write)

    The 0-base index of the selected button. The ButtonBar can have a single selected item in its dataProvider, represented by the selectedIndex. When the selectedIndex changes, a "change" event is dispatched.

    selectedItem

    selectedItem:Object
    (read)

    The item at the selectedIndex in the DataProvider.

    spacing

    spacing:Number
    (read,write)

    The spacing between each item in pixels. Spacing can be set to a negative value to overlap items.

    Instance methods

    handleInput

    function handleInput (
    details:InputDetails, pathToFocus:Array) : Boolean

    Handle input from the game, via controllers or keyboard. The default handleInput will handle standalone and composite components.
    Parameters:
    details :
    An InputDetails object containing details from the interaction.
    pathToFocus:
    A list of children in the focus path that are below this component. Components are responsible for calling handleInput() on the next component in the pathToFocus unless they choose to intercept the call.
    Overrides:

    invalidateData

    function invalidateData (
    ) : Void

    itemToLabel

    function itemToLabel (
    item:Object) : String

    Convert an item to a label string using the labelField and labelFunction. If the item is not an object, then it will be converted to a string, and returned.
    Parameters:
    item:
    The item to convert to a label.
    Returns:
    • The converted label string.
    See also: